.TH rtapi_open_as_root "3rtapi" "" "LinuxCNC Documentation" "RTAPI"
.SH NAME

rtapi_open_as_root \- Open a file with "root" privilege

.SH SYNTAX
.nf
.B #include <rtapi.h>
.HP
.BI "int rtapi_open_as_root(const char " *filename ", int " "flags)"
.fi
.SH ARGUMENTS
.IP \fIfilename\fR
The filename to open, as in \fBopen(2)\fR.  Note that rtapi has no well-defined
"current directory", so this should be an absolute path, but this is not
enforced.
.IP \fIflags\fR
The open flags, as in \fBopen(2)\fR.  Should never include bits that open or
create files (e.g., O_CREAT, O_APPEND, etc) as this API is not intended for
creating or writing files, but this is not enforced.

.SH DESCRIPTION
In "uspace" realtime, root privileges are dropped whenever possible.  This API
temporarily switches on root priveleges to open a file, and switches them
off before returning.  This can be useful for example when accessing device
nodes or memory-mapped I/O.

In the case of PCI devices on x86 and x86-64 systems, prefer the linux-style
PCI interfaces provided in \fB<rtapi_pci.h>\fR.

.SH RETURN VALUE
In case of success, the nonnegative file descriptor opened.  If the caller does
not close it, it remains open until rtapi_app exits.

In case of failure, a negative errno value.

.SH REALTIME CONSIDERATIONS
Call only from realtime initcode in "uspace" realtime.

.SH SEE ALSO
\fBopen(2)\fR, \fBrtapi_pci(3)\fR
